Deepgram/Models/Agent/v2/WebSocket/UserStartedSpeakingResponse.cs (1)

17-23: Optimize ToString implementation and add missing using directives.

The current implementation has several potential issues:

1. Missing using directives for System.Text.Json and System.Text.RegularExpressions
2. No null check before serialization
3. Unnecessary use of Regex.Unescape on every call
4. Could benefit from caching since the object is immutable

Add these using directives at the top of the file:

+using System.Text.Json;
+using System.Text.RegularExpressions;

Consider optimizing the implementation:

+    private string? _cachedString;
+
     /// <summary>
     /// Override ToString method to serialize the object
     /// </summary>
     public override string ToString()
     {
-        return Regex.Unescape(JsonSerializer.Serialize(this, JsonSerializeOptions.DefaultOptions));
+        return _cachedString ??= JsonSerializer.Serialize(this, JsonSerializeOptions.DefaultOptions);
     }

Note: Removed Regex.Unescape as it's typically not needed for JSON serialization unless you're dealing with special characters that need unescaping.

Deepgram/Models/Agent/v2/WebSocket/AgentType.cs (1)

9-28: Add XML documentation and consider enum value organization.

The enum implementation could be improved in several ways:

1. Add XML documentation for the enum and its values to support IntelliSense.
2. Explicitly set values for agent-specific states to prevent issues if WebSocketType values change.
3. Consider grouping related states using regions or comments.

Here's a suggested implementation:

+/// <summary>
+/// Represents the various states and message types in the agent WebSocket communication.
+/// </summary>
 public enum AgentType
 {
     // Base WebSocket states
     Open = WebSocketType.Open,
     Close = WebSocketType.Close,
     Unhandled = WebSocketType.Unhandled,
     Error = WebSocketType.Error,
 
     // Agent conversation states
-    Welcome,
-    ConversationText,
-    UserStartedSpeaking,
-    AgentThinking,
+    Welcome = 100,
+    ConversationText = 101,
+    UserStartedSpeaking = 102,
+    AgentThinking = 103,
 
     // Function calling states
-    FunctionCallRequest,
-    FunctionCalling,
+    FunctionCallRequest = 200,
+    FunctionCalling = 201,
 
     // Audio states
-    AgentStartedSpeaking,
-    AgentAudioDone,
-    Audio,
+    AgentStartedSpeaking = 300,
+    AgentAudioDone = 301,
+    Audio = 302,
 
     // Configuration states
-    InjectionRefused,
-    SettingsApplied,
-    InstructionsUpdated,
-    SpeakUpdated,
+    InjectionRefused = 400,
+    SettingsApplied = 401,
+    InstructionsUpdated = 402,
+    SpeakUpdated = 403,
 }

Deepgram/Models/Agent/v2/WebSocket/Audio.cs (1)

7-16: Consider making properties immutable for thread safety.

The record type suggests immutability, but the properties have public setters. For thread safety and to better align with record semantics, consider making the properties init-only.

-    public Input Input { get; set; } = new Input();
+    public Input Input { get; init; } = new Input();

-    public Output Output { get; set; } = new Output();
+    public Output Output { get; init; } = new Output();

Deepgram/Models/Agent/v2/WebSocket/Output.cs (2)

9-15: Document the significance of default values.

The default values ("linear16" for Encoding and 24000 for SampleRate) seem to be magic numbers. Consider:

1. Adding XML documentation to explain their significance
2. Using constants to improve maintainability

+    /// <summary>
+    /// Default audio encoding format compatible with Deepgram's voice agent API.
+    /// </summary>
+    private const string DefaultEncoding = "linear16";
+
+    /// <summary>
+    /// Default sample rate (in Hz) for optimal voice processing.
+    /// </summary>
+    private const long DefaultSampleRate = 24000;

-    public string Encoding { get; set; } = "linear16";
+    public string Encoding { get; set; } = DefaultEncoding;

-    public long? SampleRate { get; set; } = 24000;
+    public long? SampleRate { get; set; } = DefaultSampleRate;

---

17-23: Add validation for Bitrate property.

Consider adding validation to ensure the Bitrate value is positive when set.

+    private long? _bitrate;

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("bitrate")]
-    public long? Bitrate { get; set; }
+    public long? Bitrate
+    {
+        get => _bitrate;
+        set
+        {
+            if (value.HasValue && value.Value <= 0)
+                throw new ArgumentOutOfRangeException(nameof(value), "Bitrate must be positive");
+            _bitrate = value;
+        }
+    }

Deepgram/Clients/Agent/v2/Websocket/Client.cs (8)

18-25: Add XML summary for the constructor.
The constructor lacks an XML doc comment explaining its purpose, parameters, and usage. Providing it helps maintain consistent documentation and improves clarity for consumers of this class.

 /// <param name="apiKey">Required DeepgramApiKey</param>
 /// <param name="deepgramClientOptions"><see cref="IDeepgramClientOptions"/> for HttpClient Configuration</param>
+/// <summary>
+/// Initializes a new instance of the <see cref="Client"/> class, setting up
+/// the Deepgram API key and client options for Agent WebSocket communication.
+/// </summary>
 public Client(string? apiKey = null, IDeepgramClientOptions? options = null) : base(apiKey, options)
 {
     Log.Verbose("AgentWSClient", "ENTER");

---

27-44: Align event naming or add individual summaries.
The private events from _audioReceived to _speakUpdatedReceived share a single documentation snippet indicating “Fires when an event is received,” but each event actually targets a different response type. To make the code more self-explanatory, add or adjust comments to clarify when each event is fired and its intended usage.

---

105-129: Consolidate wrapped event subscriptions for typed “Open” / “Close” / “Error” / “Unhandled” events.
Each of these methods follows a similar pattern: create a wrapped handler, cast arguments, and subscribe via the base method. Consider creating a helper method to reduce duplication and improve readability.

-private async Task<bool> SubscribeForCommonEvent<TCommon, TSpecific>(
-    EventHandler<TSpecific> userHandler,
-    Func<Common.TCommon, TSpecific> castFunc)
-{
-    // code to wrap and subscribe
-}

Also applies to: 389-410

---

135-387: Consider adding unsubscribe support & a unified pattern for these subscription methods.
All subscription methods add their handlers to private events but never provide an unsubscribe mechanism. If a consumer repeatedly subscribes to the same event type, memory leaks or unexpected behavior may occur. Additionally, these subscription methods share repeated code blocks. Refactoring them into a common “subscribe event” helper (or using a dictionary-based approach) would reduce duplication and potential confusion.

---

483-523: Key concurrency detail in keep-alive loop.
The loop sleeps for a hard-coded 5 seconds and continues indefinitely until disconnected or canceled. Consider making the interval configurable. Also ensure that _cancellationTokenSource is disposed once completed.

---

554-555: Typo in log message “Excepton”.
Minor spelling error in the log message could cause confusion during troubleshooting or searching logs.

-Log.Verbose("ProcessDataReceived", $"Excepton: {ex}");
+Log.Verbose("ProcessDataReceived", $"Exception: {ex}");

---

560-809: Handle invalid or missing “type” gracefully in the switch statement.
When data.RootElement.GetProperty("type") is missing or invalid, Enum.Parse will fail with an exception. To improve robustness, consider using Enum.TryParse and handle unrecognized event types more gracefully.

-var val = Enum.Parse(typeof(AgentType), data.RootElement.GetProperty("type").GetString()!);
+if (!Enum.TryParse<AgentType>(data.RootElement.GetProperty("type").GetString(), out var val))
+{
+    Log.Warning("ProcessTextMessage", "Received unknown or invalid AgentType.");
+    base.ProcessTextMessage(result, ms);
+    return;
+}

---

835-858: Prevent potential double slash in URI construction.
When appending the UriSegments.AGENT constant to baseAddress, ensure no extra slash is added if baseAddress already ends with one. This avoids issues with misconfigured endpoints or future changes to UriSegments.AGENT.

-if (baseAddress.EndsWith("/"))
-    return new Uri($"{baseAddress}{UriSegments.AGENT}");
-else
-    return new Uri($"{baseAddress}/{UriSegments.AGENT}");
+if (!baseAddress.EndsWith("/"))
+{
+    baseAddress += "/";
+}
+return new Uri($"{baseAddress}{UriSegments.AGENT}");

Deepgram/Clients/Agent/v2/Websocket/ResponseEvent.cs (1)

7-10: Clarify usage of primary constructor vs. record syntax.
C# primary constructors are typically used in records. Given this class inherits EventArgs, consider using a standard class or record instead. If immutability is desired, a record with read-only properties might be preferable. Additionally, a brief summary comment clarifying usage would help.

-public class ResponseEvent<T>(T? response) : EventArgs
+/// <summary>
+/// Encapsulates an event response of type T.
+/// </summary>
+public class ResponseEvent<T> : EventArgs
+{
+    public ResponseEvent(T? response)
+    {
+        Response = response;
+    }
+
     public T? Response { get; set; }
 }

Deepgram/AgentWebSocketClient.cs (1)

13-18: Add summary doc & rename constructor parameters to match base usage.
The constructor lacks an XML doc comment. Also, for clarity, consider naming the parameter options instead of deepgramClientOptions, mirroring the base constructor’s signature. This can reduce confusion for SDK users.

 /// <summary>
 /// Implements the latest supported version of the Agent Client.
 /// </summary>
 public class AgentWebSocketClient : Client
 {
-    public AgentWebSocketClient(string apiKey = "", DeepgramWsClientOptions? deepgramClientOptions = null)
-        : base(apiKey, deepgramClientOptions)
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentWebSocketClient"/> class for contemporary Deepgram agent usage.
+    /// </summary>
+    public AgentWebSocketClient(string apiKey = "", DeepgramWsClientOptions? options = null)
+        : base(apiKey, options)
     {
     }
 }

Deepgram/Clients/Agent/v2/Websocket/UriSegments.cs (2)

9-11: Consider making the agent URI configurable.

While hardcoding "agent.deepgram.com" works for production, it might limit testing against different environments. Consider making this configurable through environment variables or configuration settings.

---

7-16: Add XML documentation for better IntelliSense support.

Consider adding XML documentation to describe the purpose and usage of these constants.

 public static class UriSegments
 {
+    /// <summary>
+    /// The base URI for Deepgram's agent API endpoint.
+    /// </summary>
     public const string AGENT_URI = "agent.deepgram.com";

+    /// <summary>
+    /// The agent endpoint segment used in API routes.
+    /// </summary>
     public const string AGENT = "agent";
 }

Deepgram/Models/Agent/v2/WebSocket/Provider.cs (2)

9-11: Add XML documentation for the Type property.

Add XML documentation to describe the expected values and purpose of the Type property.

+    /// <summary>
+    /// Gets or sets the provider type.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("type")]
     public string Type { get; set; }

---

7-12: Consider using an enum for the Type property.

Using a string for Type could lead to runtime errors if invalid values are provided. Consider using an enum to enforce valid provider types at compile-time.

+public enum ProviderType
+{
+    [JsonPropertyName("type1")]
+    Type1,
+    [JsonPropertyName("type2")]
+    Type2,
+    // Add other valid types
+}

 public record Provider
 {
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("type")]
-    public string Type { get; set; }
+    public ProviderType Type { get; set; }

Deepgram/Models/Agent/v2/WebSocket/Properties.cs (2)

13-13: Remove extra blank line.

Remove the unnecessary blank line to maintain consistent formatting.

---

9-11: Add XML documentation for the Item property.

Add XML documentation to describe the purpose and nullable nature of the Item property.

+    /// <summary>
+    /// Gets or sets the item associated with these properties.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("item")]
     public Item? Item { get; set; }

Deepgram/Models/Agent/v2/WebSocket/Listen.cs (2)

11-11: Consider making the model version configurable.

The default model version "nova-2" is hardcoded. Consider making this configurable to support future model versions without code changes.

---

9-11: Add XML documentation and validation for the Model property.

Add XML documentation and consider adding validation to ensure the model version is supported.

+    /// <summary>
+    /// Gets or sets the model version to use for speech recognition.
+    /// Default value is "nova-2".
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("model")]
-    public string Model { get; set; } = "nova-2";
+    public string Model
+    {
+        get => _model;
+        set
+        {
+            if (string.IsNullOrEmpty(value))
+                throw new ArgumentException("Model version cannot be null or empty");
+            _model = value;
+        }
+    }
+
+    private string _model = "nova-2";

Deepgram/Models/Agent/v2/WebSocket/Speak.cs (2)

7-12: Add XML documentation and consider making the model name configurable.

The Model property lacks XML documentation. Additionally, the hardcoded model name "aura-asteria-en" should ideally be configurable or defined as a constant.

 public record Speak
 {
+    /// <summary>
+    /// The voice model to use for speech synthesis.
+    /// </summary>
+    /// <remarks>
+    /// Available models:
+    /// - aura-asteria-en: Default English voice model
+    /// </remarks>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("model")]
-    public string Model { get; set; } = "aura-asteria-en";
+    public string Model { get; set; } = SpeakModels.Default;
 }

+ public static class SpeakModels
+ {
+     public const string Default = "aura-asteria-en";
+ }

---

16-19: Add return value documentation for ToString.

The XML documentation for the ToString override should include information about the return value.

     /// <summary>
     /// Override ToString method to serialize the object
     /// </summary>
+    /// <returns>A JSON string representation of the object.</returns>

Deepgram/Models/Agent/v2/WebSocket/KeepAliveSchema.cs (1)

7-15: Consider using a record and fix documentation.

1. The XML documentation incorrectly mentions "SettingsConfiguration".
2. Since Type is effectively readonly, consider:
   • Making this a record
   • Using init-only property

- public class KeepAliveSchema
+ public record KeepAliveSchema
 {
     /// <summary>
-    /// SettingsConfiguration event type.
+    /// The keep-alive message type.
     /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("type")]
-    public string? Type { get; } = AgentClientTypes.KeepAlive;
+    public string? Type { get; init; } = AgentClientTypes.KeepAlive;

Deepgram/Models/Agent/v2/WebSocket/Header.cs (1)

17-23: Add return value documentation for ToString.

The XML documentation for the ToString override should include information about the return value.

     /// <summary>
     /// Override ToString method to serialize the object
     /// </summary>
+    /// <returns>A JSON string representation of the object.</returns>

Deepgram/Models/Agent/v2/WebSocket/Item.cs (1)

9-15: Add XML documentation for properties.

Properties lack XML documentation. Add summary tags to describe their purpose and usage.

 public record Item
 {
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("type")]
+    /// <summary>
+    /// Gets or sets the type of the item.
+    /// </summary>
     public string? Type { get; set; }

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("description")]
+    /// <summary>
+    /// Gets or sets the description of the item.
+    /// </summary>
     public string? Description { get; set; }

Deepgram/Models/Agent/v2/WebSocket/Context.cs (1)

13-15: Add XML documentation for properties.

Properties lack XML documentation. Add summary tags to describe their purpose and usage.

+    /// <summary>
+    /// Gets or sets the list of messages in the content.
+    /// </summary>
     public List<object>? Messages { get; set; }

+    /// <summary>
+    /// Gets or sets a value indicating whether replay is enabled.
+    /// </summary>
     public bool? Replay { get; set; }

Deepgram/Models/Agent/v2/WebSocket/SettingsAppliedResponse.cs (3)

1-1: Update copyright year to 2024.

The copyright year should be 2024 as we're currently in January 2025.

-// Copyright 2025 Deepgram .NET SDK contributors. All Rights Reserved.
+// Copyright 2024 Deepgram .NET SDK contributors. All Rights Reserved.

---

9-11: Fix incorrect XML documentation.

The XML documentation refers to "SettingsConfiguration" instead of "SettingsApplied".

    /// <summary>
-   /// SettingsConfiguration event type.
+   /// SettingsApplied event type.
    /// </summary>

---

17-20: Enhance XML documentation for ToString method.

Add return value documentation using <returns> tag.

    /// <summary>
    /// Override ToString method to serialize the object
    /// </summary>
+   /// <returns>A JSON string representation of the object.</returns>

Deepgram/Models/Agent/v2/WebSocket/Input.cs (3)

9-11: Add XML documentation for Encoding property.

Document the property's purpose and default value.

+   /// <summary>
+   /// Gets or sets the audio encoding format.
+   /// Default value is "linear16".
+   /// </summary>
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    [JsonPropertyName("encoding")]
    public string Encoding { get; set; } = "linear16";

---

13-15: Add XML documentation for SampleRate property.

Document the property's purpose and default value.

+   /// <summary>
+   /// Gets or sets the audio sample rate in Hz.
+   /// Default value is 24000.
+   /// </summary>
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    [JsonPropertyName("sample_rate")]
    public long? SampleRate { get; set; } = 24000;

---

7-16: Add input validation for Encoding and SampleRate properties.

Consider adding validation to ensure valid values are set:

1. Encoding should be validated against supported formats
2. SampleRate should be within acceptable range

 public record Input
 {
+    private string _encoding = "linear16";
+    private long? _sampleRate = 24000;
+
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("encoding")]
-    public string Encoding { get; set; } = "linear16";
+    public string Encoding
+    {
+        get => _encoding;
+        set
+        {
+            if (!IsValidEncoding(value))
+                throw new ArgumentException("Invalid encoding format", nameof(value));
+            _encoding = value;
+        }
+    }

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("sample_rate")]
-    public long? SampleRate { get; set; } = 24000;
+    public long? SampleRate
+    {
+        get => _sampleRate;
+        set
+        {
+            if (value.HasValue && (value < 8000 || value > 48000))
+                throw new ArgumentException("Sample rate must be between 8000 and 48000 Hz", nameof(value));
+            _sampleRate = value;
+        }
+    }
+
+    private static bool IsValidEncoding(string encoding) =>
+        encoding?.ToLowerInvariant() switch
+        {
+            "linear16" or "mulaw" or "alaw" => true,
+            _ => false
+        };

Deepgram/Models/Agent/v2/WebSocket/InjectionRefusedResponse.cs (2)

1-1: Update copyright year to 2024.

The copyright year should be 2024 as we're currently in January 2025.

-// Copyright 2025 Deepgram .NET SDK contributors. All Rights Reserved.
+// Copyright 2024 Deepgram .NET SDK contributors. All Rights Reserved.

---

9-11: Fix incorrect XML documentation.

The XML documentation refers to "SettingsConfiguration" instead of "InjectionRefused".

    /// <summary>
-   /// SettingsConfiguration event type.
+   /// InjectionRefused event type.
    /// </summary>

Deepgram/Models/Agent/v2/WebSocket/FunctionCallRequestResponse.cs (2)

9-11: Fix incorrect XML documentation.

The XML documentation refers to "SettingsConfiguration" instead of "FunctionCallRequest".

    /// <summary>
-   /// SettingsConfiguration event type.
+   /// FunctionCallRequest event type.
    /// </summary>

---

1-26: Ensure consistency across WebSocket response models.

Consider the following architectural improvements:

1. Standardize property mutability:
   • Input.cs uses mutable properties
   • Other models use init-only properties
2. Create a base response class/interface:
   • All models have Type and ToString() implementation
   • Common serialization logic could be shared
3. Add XML documentation templates:
   • Standardize documentation format
   • Include examples in documentation

Example base class:

public abstract record AgentResponseBase
{
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    [JsonPropertyName("type")]
    [JsonConverter(typeof(JsonStringEnumConverter))]
    public AgentType? Type { get; init; }

    public override string ToString() =>
        Regex.Unescape(JsonSerializer.Serialize(this, JsonSerializeOptions.DefaultOptions));
}

Deepgram/Models/Agent/v2/WebSocket/UpdateSpeakSchema.cs (3)

9-14: Fix incorrect XML documentation for Type property

The XML comment incorrectly states "SettingsConfiguration event type" when it should describe the UpdateSpeak event type.

     /// <summary>
-    /// SettingsConfiguration event type.
+    /// UpdateSpeak event type.
     /// </summary>

---

16-18: Add XML documentation for Model property

Missing XML documentation for the Model property. Add a summary describing its purpose and any constraints.

+    /// <summary>
+    /// The model to be used for speech synthesis.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("model")]

---

23-26: Add error handling to ToString method

The ToString method should handle potential serialization errors to prevent runtime exceptions.

     public override string ToString()
     {
-        return Regex.Unescape(JsonSerializer.Serialize(this, JsonSerializeOptions.DefaultOptions));
+        try
+        {
+            return Regex.Unescape(JsonSerializer.Serialize(this, JsonSerializeOptions.DefaultOptions));
+        }
+        catch (JsonException ex)
+        {
+            return $"{{\"error\": \"Failed to serialize {nameof(UpdateSpeakSchema)}: {ex.Message}\"}}";
+        }
     }

Deepgram/Models/Agent/v2/WebSocket/InjectAgentMessageSchema.cs (1)

16-18: Add XML documentation for Message property

Missing XML documentation for the Message property.

+    /// <summary>
+    /// The message to be injected into the agent's processing workflow.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("message")]

Deepgram/Models/Agent/v2/WebSocket/UpdateInstructionsSchema.cs (1)

16-18: Add XML documentation for Instructions property

Missing XML documentation for the Instructions property.

+    /// <summary>
+    /// The updated instructions for the agent's behavior.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("instructions")]

Deepgram/Models/Agent/v2/WebSocket/WelcomeResponse.cs (2)

17-19: Add XML documentation for SessionId property

Missing XML documentation for the SessionId property.

+    /// <summary>
+    /// The unique identifier for the WebSocket session.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("session_id")]

---

1-28: Consider introducing a base class for common functionality

All schema/response classes share common patterns for JSON serialization and ToString implementation. Consider extracting these into a base class or interface to promote DRY principles and ensure consistent error handling.

Example base class:

public abstract class WebSocketMessageBase
{
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    [JsonPropertyName("type")]
    public abstract string? Type { get; }

    public override string ToString()
    {
        try
        {
            return Regex.Unescape(JsonSerializer.Serialize(this, JsonSerializeOptions.DefaultOptions));
        }
        catch (JsonException ex)
        {
            return $"{{\"error\": \"Failed to serialize {GetType().Name}: {ex.Message}\"}}";
        }
    }
}

Deepgram/Models/Agent/v2/WebSocket/AgentThinkingResponse.cs (2)

9-11: Fix incorrect XML documentation.

The XML comment for the Type property incorrectly mentions "SettingsConfiguration" instead of "AgentThinking".

-    /// SettingsConfiguration event type.
+    /// The type of the agent event, which is AgentThinking.

---

17-19: Add XML documentation for the Content property.

Missing XML documentation for the Content property.

+    /// <summary>
+    /// The content of the agent's thinking response.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]

Deepgram/Models/Agent/v2/WebSocket/Agent.cs (3)

9-11: Add XML documentation for the Listen property.

Missing XML documentation for the Listen property.

+    /// <summary>
+    /// Configuration for the agent's listening capabilities.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]

---

13-15: Add XML documentation for the Think property.

Missing XML documentation for the Think property.

+    /// <summary>
+    /// Configuration for the agent's thinking capabilities.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]

---

17-19: Add XML documentation for the Speak property.

Missing XML documentation for the Speak property.

+    /// <summary>
+    /// Configuration for the agent's speaking capabilities.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]

Deepgram/Models/Agent/v2/WebSocket/FunctionCallingResponse.cs (2)

9-11: Fix incorrect XML documentation.

The XML comment for the Type property incorrectly mentions "SettingsConfiguration" instead of "FunctionCalling".

-    /// SettingsConfiguration event type.
+    /// The type of the agent event, which is FunctionCalling.

---

17-19: Add XML documentation for the SessionId property.

Missing XML documentation for the SessionId property.

+    /// <summary>
+    /// The unique identifier for the current session.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]

Deepgram/Models/Agent/v2/WebSocket/Parameters.cs (3)

13-15: Add XML documentation for the Properties property.

Missing XML documentation for the Properties property.

+    /// <summary>
+    /// The properties configuration for the parameters.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]

---

17-19: Add XML documentation for the ParametersRequired property.

Missing XML documentation for the ParametersRequired property.

+    /// <summary>
+    /// The list of required parameter names.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]

---

21-22: Remove extra blank lines.

There are two consecutive blank lines between properties and the ToString method.

     public List<string>? ParametersRequired { get; set; }

-
-
     /// <summary>

Deepgram/Models/Agent/v2/WebSocket/AudioResponse.cs (2)

7-30: Add XML documentation for the Dispose method.

The class has good documentation overall, but the Dispose method is missing XML documentation. Consider adding it to maintain consistency.

+    /// <summary>
+    /// Disposes of the underlying stream if it exists.
+    /// </summary>
     public void Dispose()
     {
         Stream?.Dispose();
         Stream = null;
     }

---

22-23: Consider formalizing the note about ToString().

The note about ToString() could be more formal using XML documentation.

-    // NOTE: There isn't a ToString() function because this will cause an odd Exception to be thrown:
-    // InvalidOperationException: "Timeouts are not supported on this stream."
+    /// <summary>
+    /// ToString() is intentionally not overridden as it would cause an InvalidOperationException
+    /// with the message "Timeouts are not supported on this stream."
+    /// </summary>

Deepgram/Models/Agent/v2/WebSocket/FunctionCallResponseSchema.cs (3)

9-11: Fix incorrect XML documentation.

The documentation for the Type property incorrectly states "SettingsConfiguration event type" when it should describe the function call response type.

     /// <summary>
-    /// SettingsConfiguration event type.
+    /// The type of the function call response.
     /// </summary>

---

16-22: Add XML documentation for missing properties.

The FunctionCallId and Output properties are missing XML documentation.

+    /// <summary>
+    /// The unique identifier of the function call.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("function_call_id")]
     public string? FunctionCallId { get; set; }

+    /// <summary>
+    /// The output returned by the function call.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("output")]
     public string? Output { get; set; }

---

7-31: Consider using a record for immutability.

Since this class represents a response schema, consider making it immutable by converting it to a record with init-only properties.

-public class FunctionCallResponseSchema
+public record FunctionCallResponseSchema
 {
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("type")]
-    public string? Type { get; } = AgentClientTypes.FunctionCallResponse;
+    public string? Type { get; init; } = AgentClientTypes.FunctionCallResponse;

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("function_call_id")]
-    public string? FunctionCallId { get; set; }
+    public string? FunctionCallId { get; init; }

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("output")]
-    public string? Output { get; set; }
+    public string? Output { get; init; }

Deepgram/Models/Agent/v2/WebSocket/ConversationTextResponse.cs (3)

9-11: Fix incorrect XML documentation.

The documentation for the Type property incorrectly states "SettingsConfiguration event type" when it should describe the conversation text type.

     /// <summary>
-    /// SettingsConfiguration event type.
+    /// The type of the conversation text response.
     /// </summary>

---

17-23: Add XML documentation for missing properties.

The Role and Content properties are missing XML documentation.

+    /// <summary>
+    /// The role of the conversation participant (e.g., user, assistant).
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("role")]
     public string? Role { get; set; }

+    /// <summary>
+    /// The content of the conversation message.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("content")]
     public string? Content { get; set; }

---

7-32: Consider using init-only properties.

Since this is already a record, consider making the properties init-only for better immutability.

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("role")]
-    public string? Role { get; set; }
+    public string? Role { get; init; }

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("content")]
-    public string? Content { get; set; }
+    public string? Content { get; init; }

Deepgram/Models/Agent/v2/WebSocket/Think.cs (3)

9-23: Add XML documentation for all properties.

All properties are missing XML documentation.

+    /// <summary>
+    /// The provider configuration for the think operation.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("provider")]
     public Provider? Provider { get; set; } = new Provider();

+    /// <summary>
+    /// The model to be used for thinking.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("model")]
     public string? Model { get; set; }

+    /// <summary>
+    /// The instructions for the think operation.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("instructions")]
     public string? Instructions { get; set; }

+    /// <summary>
+    /// The list of functions available during the think operation.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("functions")]
     public List<Function>? Functions { get; set; }

---

25-26: Remove unnecessary blank lines.

There are two consecutive blank lines that should be removed.

     public List<Function>? Functions { get; set; }

-
-
     /// <summary>

---

7-34: Consider using init-only properties.

Since this is a record, consider making the properties init-only for better immutability.

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("provider")]
-    public Provider? Provider { get; set; } = new Provider();
+    public Provider? Provider { get; init; } = new Provider();

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("model")]
-    public string? Model { get; set; }
+    public string? Model { get; init; }

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("instructions")]
-    public string? Instructions { get; set; }
+    public string? Instructions { get; init; }

     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("functions")]
-    public List<Function>? Functions { get; set; }
+    public List<Function>? Functions { get; init; }

Deepgram/Models/Agent/v2/WebSocket/SettingsConfigurationSchema.cs (2)

16-26: Add XML documentation for public properties.

The Audio, Agent, and Context properties are missing XML documentation. Adding documentation would improve API usability and maintain consistency with other documented members.

---

31-34: Consider optimizing ToString() implementation.

The current implementation uses Regex.Unescape which might be unnecessary overhead if the serialized JSON doesn't contain escaped characters. Consider using JsonSerializer.Serialize directly unless there's a specific need for unescaping.

-        return Regex.Unescape(JsonSerializer.Serialize(this, JsonSerializeOptions.DefaultOptions));
+        return JsonSerializer.Serialize(this, JsonSerializeOptions.DefaultOptions);

Deepgram/Models/Agent/v2/WebSocket/AgentStartedSpeakingResponse.cs (1)

9-11: Fix incorrect XML documentation.

The XML documentation for the Type property incorrectly states "SettingsConfiguration event type" when it should describe the agent started speaking event type.

-    /// SettingsConfiguration event type.
+    /// The type of the event, indicating that the agent has started speaking.

Deepgram/Clients/Interfaces/v2/IAgentWebSocketClient.cs (1)

121-133: Clarify the distinction between binary and text messages.

The documentation doesn't clearly explain the difference between SendBinary and SendMessage. Both accept byte arrays but their purposes seem different. Consider adding detailed documentation about when to use each method.

examples/agent/websocket/simple/Program.cs (2)

47-47: Extract magic number to constant.

The hardcoded value 7 should be extracted to a named constant for better maintainability.

+private const int AUDIO_FILE_TIMEOUT_SECONDS = 7;
-if (DateTime.Now.Subtract(lastAudioTime).TotalSeconds > 7)
+if (DateTime.Now.Subtract(lastAudioTime).TotalSeconds > AUDIO_FILE_TIMEOUT_SECONDS)

---

210-218: Enhance cleanup error handling.

While resources are properly disposed, the error handling could be more robust.

-// Stop the microphone
-microphone.Stop();
+try
+{
+    Console.WriteLine("Stopping microphone...");
+    microphone.Stop();
+    
+    Console.WriteLine("Stopping WebSocket connection...");
+    await agentClient.Stop();
+    
+    Console.WriteLine("Terminating libraries...");
+    Deepgram.Microphone.Library.Terminate();
+    Deepgram.Library.Terminate();
+    
+    Console.WriteLine("Cleanup completed successfully");
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"Error during cleanup: {ex.Message}");
+    // Consider logging to file or telemetry service
+}

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

Learnt from: dvonthenen
PR: deepgram/deepgram-dotnet-sdk#316
File: Deepgram/Models/Speak/v1/WebSocket/ControlMessage.cs:7-8
Timestamp: 2024-11-12T11:33:12.821Z
Learning: Primary constructor syntax in class declarations, such as `public class ClassName(Type parameter)`, is valid starting from C# 12.

Learnt from: dvonthenen
PR: deepgram/deepgram-dotnet-sdk#347
File: Deepgram/ClientFactory.cs:146-161
Timestamp: 2024-11-12T11:33:27.266Z
Learning: In `Deepgram/ClientFactory.cs`, the method `CreateListenWebSocketClient(int version, ...)` is intentionally returning `object` as a placeholder because there is only one version of the client. It should not be suggested to change the return type until multiple versions are implemented.

examples/agent/websocket/simple/Program.cs (5)

30-31: ⚠️ Potential issue

Add API key validation and error handling.

The code passes an empty API key to CreateAgentWebSocketClient. This will cause runtime issues.

---

51-55: 🛠️ Refactor suggestion

Add directory cleanup and exception handling for file operations.

File operations should be wrapped in try-catch blocks and old files should be cleaned up.

---

127-186: 🛠️ Refactor suggestion

Enhance event handlers with proper error handling and logging.

The current event handlers only log the event type. Consider adding proper error handling, detailed logging of event data, and retry logic for recoverable errors.

---

191-191: ⚠️ Potential issue

Invalid OpenAI model name "gpt-4o-mini".

The model name appears to be a typo. OpenAI doesn't have a model named "gpt-4o-mini".

---

196-201: 🛠️ Refactor suggestion

Enhance connection error handling.

The connection failure handling is minimal. Consider adding retry logic and more detailed error information.

Deepgram/Clients/Agent/v2/Websocket/Client.cs (4)

51-53: Unused parameter addons
The addons parameter here is never used in the method. If this is intentional, consider removing it or adding documentation explaining why it exists.

---

105-434: Unify base subscription vs. local event subscription
Not all subscribe methods call base.Subscribe; some attach directly to private event fields, while others rely on the base call. This discontinuity complicates event unsubscription and may lead to inconsistent code paths.

---

577-577: Dispose parsed JsonDocument
JsonDocument is disposable. Wrapping it with a using var data = JsonDocument.Parse(response); ensures proper disposal for improved memory management.

---

849-855: Compile the Regex for better performance
Using new Regex(pattern, RegexOptions.Compiled) can provide performance benefits if the same pattern is used multiple times. Though minor for single usage, it’s a simple improvement.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

Learnt from: dvonthenen
PR: deepgram/deepgram-dotnet-sdk#347
File: Deepgram/ClientFactory.cs:146-161
Timestamp: 2024-11-12T11:33:27.266Z
Learning: In `Deepgram/ClientFactory.cs`, the method `CreateListenWebSocketClient(int version, ...)` is intentionally returning `object` as a placeholder because there is only one version of the client. It should not be suggested to change the return type until multiple versions are implemented.

Deepgram/Clients/Interfaces/v2/IAgentWebSocketClient.cs (1)

143-143: ⚠️ Potential issue

Fix inconsistent parameter naming.

The _cancellationToken parameter name starts with an underscore, which is inconsistent with C# naming conventions and other parameters in the interface.

Also applies to: 165-165, 173-173

Deepgram/Clients/Interfaces/v2/IAgentWebSocketClient.cs (3)

9-12: Fix interface documentation.

The XML comment incorrectly states that the interface "Implements" version 2. Interfaces define or specify contracts rather than implement them.

-/// Implements version 2 of the Agent Client.
+/// Defines the contract for version 2 of the Agent Client.

---

18-19: Consider reordering parameters for better usability.

The Connect method's parameter order could be improved by grouping required parameters first, followed by optional parameters.

-public Task<bool> Connect(SettingsConfigurationSchema options, CancellationTokenSource? cancelToken = null, Dictionary<string, string>? addons = null,
-    Dictionary<string, string>? headers = null);
+public Task<bool> Connect(
+    SettingsConfigurationSchema options,
+    Dictionary<string, string>? headers = null,
+    Dictionary<string, string>? addons = null,
+    CancellationTokenSource? cancelToken = null);

---

12-13: Add thread safety and exception documentation.

Consider adding interface-level documentation about:

1. Thread safety guarantees
2. Common exceptions that might be thrown
3. Any specific implementation requirements

This will help implementers better understand the contract requirements.

 /// <summary>
 /// Defines the contract for version 2 of the Agent Client.
+/// </summary>
+/// <remarks>
+/// Implementations of this interface should be thread-safe.
+/// Common exceptions that may be thrown include:
+/// <list type="bullet">
+/// <item><description>InvalidOperationException when operations are called in invalid states</description></item>
+/// <item><description>WebSocketException for connection-related issues</description></item>
+/// </list>
 /// </summary>
 public interface IAgentWebSocketClient

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

Deepgram/Models/Agent/v2/WebSocket/Context.cs (1)

7-16: 🛠️ Refactor suggestion

Consider using a more specific type than List.

Using List<object> loses type safety and makes it harder to work with the messages. Consider creating a specific type for messages or using a more specific base type.

Additionally, please add XML documentation comments for the properties to describe their purpose and expected values:

+    /// <summary>
+    /// Gets or sets the list of messages in the context.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("messages")]
     public List<object>? Messages { get; set; }

+    /// <summary>
+    /// Gets or sets a value indicating whether to replay the context.
+    /// </summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     [JsonPropertyName("replay")]
     public bool? Replay { get; set; }

🧹 Nitpick comments (3)

Deepgram/Models/Agent/v2/WebSocket/Context.cs (1)

18-24: Improve error handling in ToString method.

The current implementation doesn't handle serialization errors. Consider adding try-catch block:

     public override string ToString()
     {
-        return Regex.Unescape(JsonSerializer.Serialize(this, JsonSerializeOptions.DefaultOptions));
+        try
+        {
+            return Regex.Unescape(JsonSerializer.Serialize(this, JsonSerializeOptions.DefaultOptions));
+        }
+        catch (JsonException ex)
+        {
+            return $"Error serializing {nameof(Context)}: {ex.Message}";
+        }
     }

examples/agent/websocket/simple/Program.cs (2)

51-55: Use Path.Combine for file paths and add file access error handling.

File operations should use Path.Combine for path construction and include proper error handling.

-if (File.Exists($"output_{audioFileCount}.wav"))
+var outputPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, $"output_{audioFileCount}.wav");
+if (File.Exists(outputPath))
 {
-    File.Delete($"output_{audioFileCount}.wav");
+    try
+    {
+        File.Delete(outputPath);
+    }
+    catch (IOException ex)
+    {
+        Console.WriteLine($"Error deleting file: {ex.Message}");
+        return;
+    }
 }

Also applies to: 118-122

---

38-186: Improve event handler organization and logging.

The event handlers could be better organized and include more meaningful logging:

1. Group related handlers together (e.g., agent events, audio events)
2. Add type-specific information to logs

Example for one group of handlers:

+// Agent state events
 await agentClient.Subscribe(new EventHandler<AgentStartedSpeakingResponse>((sender, e) =>
 {
-    Console.WriteLine($"----> {e} received");
+    Console.WriteLine($"Agent started speaking: SessionId={e.SessionId}");
 }));
 await agentClient.Subscribe(new EventHandler<AgentThinkingResponse>((sender, e) =>
 {
-    Console.WriteLine($"----> {e} received");
+    Console.WriteLine($"Agent thinking: SessionId={e.SessionId}");
 }));

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between eb8c0a3 and 4242619.

📒 Files selected for processing (4)

• .gitignore (1 hunks)
• Deepgram/Models/Agent/v2/WebSocket/Context.cs (1 hunks)
• examples/agent/websocket/simple/Agent.csproj (1 hunks)
• examples/agent/websocket/simple/Program.cs (1 hunks)

✅ Files skipped from review due to trivial changes (1)

• .gitignore

🔇 Additional comments (7)

examples/agent/websocket/simple/Agent.csproj (3)

1-8: LGTM! Good project configuration choices.

The project is well-configured with:

• Latest .NET 8.0 LTS version
• Nullable reference types for better type safety
• Implicit usings for cleaner code

---

15-17: LGTM! Appropriate namespace configuration.

The global using directive for the Deepgram namespace will help reduce code duplication across files.

---

10-13: Verify project reference paths.

The project references use deep relative paths (..\..\..\..\). While functional, this could be fragile if the project structure changes.

Run this script to verify the project structure:

✅ Verification successful

Project references are correctly structured

The referenced projects exist at the expected locations and the relative paths are correct for the current project structure. While the paths use multiple parent directory traversals, this is consistent with the repository's organization of example projects.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Verify project references exist and check for alternative path options

# Check if referenced projects exist
fd -e csproj -x echo "Found project: {}"

# Look for .sln files to understand solution structure
fd -e sln -x echo "Found solution: {}"

Length of output: 2635

Deepgram/Models/Agent/v2/WebSocket/Context.cs (1)

7-25: Verify the usage of JsonSerializeOptions.DefaultOptions.

Let's verify that JsonSerializeOptions.DefaultOptions is properly defined and accessible.

✅ Verification successful

JsonSerializeOptions.DefaultOptions is properly defined and widely used

The static property is correctly implemented in the internal JsonSerializeOptions class, providing consistent serialization settings across the codebase with web-compatible defaults and indented formatting.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Search for JsonSerializeOptions class definition and its DefaultOptions property
ast-grep --pattern 'class JsonSerializeOptions {
  $$$
  static $_DefaultOptions$_ {
    $$$
  }
  $$$
}'

Length of output: 107

---

Script:

#!/bin/bash
# Search for JsonSerializeOptions in all files
echo "=== Searching for JsonSerializeOptions ==="
rg -l "JsonSerializeOptions"

echo -e "\n=== Searching for JsonSerializeOptions with context ==="
rg "JsonSerializeOptions" -A 5 -B 5

echo -e "\n=== Searching for DefaultOptions in .cs files ==="
rg "DefaultOptions" --type csharp

Length of output: 67888

examples/agent/websocket/simple/Program.cs (3)

29-31: Add API key validation and error handling.

The code passes an empty API key to CreateAgentWebSocketClient. This will likely cause runtime issues when attempting to connect to the Deepgram API.

---

191-191: Invalid OpenAI model name "gpt-4o-mini".

The model name appears to be a typo. OpenAI doesn't have a model named "gpt-4o-mini".

---

198-203: Enhance connection error handling.

The connection failure handling is minimal. Consider adding retry logic and more detailed error information.